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Preface 



The purpose of this specification is to define the outward appearance and the internal 
workmgs of the gpio monolith (gpioO) for the Series 800 CiO based machines. This driver 
controls the 27114B QO AFI card as well as the 27114A QO AFI card. 

I assume that the reader understands both the I/O system and the AFI card. To acquire 
this background, the following is recommended reading: 

• HP-UX I/O Services Definition (HPIOSD), General Systems Division 

• 27114B External Reference Specification, Roseville Networks Division 

The HPIOSD explains the basic concepts of the I/O system. It must be understood before 
attempting this specification. The 27114B ERS explains how the AFI card works and can 
be used as a reference whenever card-level questions come up. 

Other useful documents are: 

• HP-UX I/O CIO Channel Adapter Manager ES, General Systems Division 

• HP-CIO Standard Document, Roseville Networks Division 

• CIO Driver Writer's Manual 

• GPIO(DEV) Manpage 

This document is organized into three major sections, an external explanation of the driver, 
a theory of operations and an internal explanation of the driver. 

The sections dealing with the external ©cplanation of the driver discuss how the driver 
communicates with the HP-UX I/O system, and how the driver is configured into the I/O 
system. 

The theory of operations section discusses each feature of the 27114B product as a whole; 
without regard to specific routines or driver organization. It is in this section that history 
(and reasons for why the features function as they do) is discussed. 

The sections dealing with the internal explanation of the driver discuss each driver routine 
in detail. 
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1. History of the AFI product 

The release 7.0 AFI product is a parallel interface product designed as a replacement for the 271 14A 
product. As such, the 27114B hardware is designed for backwards compatibility with the 271 14A 
hardware and the release 7.0 driver is designed for backwards compatibility with the Release 3.0 
driver. Ideally every customer will be on the 27114B product when 7.0 releases. Realistically, there 
will be a period of time where new hardware is running with pre-7.0 software and where old 
hardware is running with 7.0 software. 

The 27114B is intended to fix a few weakness of the 27114A. Those weaknesses are: 

• The driver can not know, in a reasonable manner, how much data exists on the 27114A's FIFO. 
Because of this, the driver can not successfully block write transactions or report accurate 
residues. 

• The 27114A can not work m a true GPIO environment. Because of this, data can be lost. (More 
on what a 'GPIO environment' means later. See the section on the transfer counter.) 

• The 27114A does not allow for early termination of data transfers. Because of this the product is 
inflexible for many emironments and at times, data is lost. 

• The 27114A must be master/controller of the handshake. Because of this, 271 14A to 27114A 
communication can not be done reliably. The inability to be a slave also makes the product 
inflexible. 



It is worthwhile to note what CIO GPIO customers wanted most from the new product, 

1st requirement: hardware compatibility 

2nd requirement: software compatibility 

3rd requirement: early termination to data transfers 

4th requirement: master and slave handshake modes 

5th requirement: more control and status lines 

6th requirement: the ability to work in a true GPIO environment 

The 271 14B and release 7.0 of the AFI driver attempt to resolve the above weaknesses within the 
prioritized constraints given. 



As of today, personnel of interest to the AFI product are, 

Bill Hooper RND development engineer 

Responsible for the AH diagnostics 
Bob Kentwortz GSY Tech Marketing/Escalations Management 

Handles AFI software hotsites. 
Michele Mansfield GSY Learning Products 

Responsible for the Programmers Guide to the AFI 
Bobbie Martinez NMC on-line support 

Handles AFI hardware hotsites. 
Pery Pearson RND development engmeer 

Helped design and now supports the 27114B. 
Le SeUers RND technical writer 

Responsible for the 27114B Technical Reference Manual 
Bill Wang RND Product Marketing 

Product manager for AFI, among other things. 
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Anders Wernblom XTTC 

A real trooper who has patiently tested the product. 

I will, of course, be happy to help in any manner. Please do not hesitate to ask. 
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2. Overview of GpioO 

The driver for the 2711B product is called gpioO. It is a monolithic manager with two distinct 
interfaces: the interface with the kernel and the interface with the low-level i/o system. A monolithic 
manager was chosen for performance reasons. 



2.1 External interface - kernel level 

The manager is entered from the kernel via system calls to open(OS), close(OS), read(OS), 
write(OS), loctl(OS) and select(OS). This is the same interface that all HP-UX LDM-level 
managers use. The interface with the low-level io system follows the message-based interface of the 
HP I/O Services Definition. 

The Channel Adapter Manager (CAM) is the lowest level of the I/O software. The CAM's 
responsibility is to transmit messages from its higher managers over the CIO channel adapter. The 
CAM and gpioO communicate via the message system. 

Users access gpioO through special files called device files that reside in the /dev directory. The 
mknod command can be used to create a device file for gpioO: 

/elc/raknod gpioO c 22 mmor_number 

Minor_number specifies the logical unit associated v^ith this de\ice file. The minor number format 
for gpioO is 



(Ibit) 


Obits) 


(4bits) 


(8blts) 


fSblts) 


D 


not.used 


pseudo 


lu^number 


not_used 



The D bit, if set, means that this device file supports diagnostic requests. The pseudo bits, only 
usable by the driver, are described later. Their use is necessary to support multiple opens of the 
same device file. 

Diagnostics are supported by gpioO via ioctl requests, providing the gpioO device file opened has the 
D bit set. This forces exclusive access to the device and allows the usage of various special ioctl 
calls. While in diagnostic mode, the user has complete control of the card. GpioO will not touch any 
register on the card unless the user requests it. The ioctls which are available only in diagnostic 
mode are explained in Appendix I. 



22 External interface - low level 

This section describes how gpioO interfaces with the CAM and the Configurator. The messages 
conveyed from gpioO to the Configurator and from gpioO to the CAM are covered, as well as the 
means whereby the CAM and ^ioO are *t>ound" together. 

This section exammes each message recognized by gpioO and its use. 
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message hiie 



direction 



description 



Configuration 
creation 
do bind req 
do bmd reply 
bind request 
bind reply 



in 

in 

out 

out 

in 



Specify the manager's operating environment 
Request manager to bind with a lower manager 
I/O configuration is complete 
Request manager to bind with a higher manager 
binding sequence is complete 



CAM 

cam request 
cam reply 
cam event 



out 

in 

in 



start a CIO dma transaction 

complete a CIO dma transaction 

informs manager of asynchronous CIO events 



Generic 
poweron req 
poweron reply 
abort event 



m 

out 

out 



Inform manager of system power recovery 
Manager completed power recovery sequence 
Prematurely stop a request from completing 



22.1 Configiiration messages 

Configuration messages are used to establish the lines of communication between gpioO and the 
CAM. Each instance of gpioO (corresponding to each AFI device adapter configured into the 
system) will receive these messages, in the sequence below. 

12.1.1 Creation message 

The CREATION.MSG is the first message gpioO will receive; it is used by I/O Services to determine 
some of gpioO's port requirements. GpioO will place certain configuration information in the 
creation Jnfo fields, such as the size of its port data area, pda, the size of its largest message, and the 
nimiber of subqueues it needs to operate. 



111.2 Do bind request message 

The next message gpioO should receive is a DO.BIND_REQ_MSG. This message, from the I/O 
Configurator, tells gpioO the port number of the lower manager that controls gpioO's hardware; this 
will always be the CAM. The information in the request that gpioO will use is the following: 



reply juhque what subqueue to send the do bmd reply to 

mgrjport'num gpioO's port number 

mgrjiwjiddrl the CIO slot of the AFI device adapter 

ImjtQTtjmm the CAM's port number 
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ZZ1.3 Bind request message 

Receipt of a DO_BIND_REQ_MSG will cause gpioO to send a BIND.REQ_MSG to the CAM, v,ith 
the following fields set: 



repfy^bg REPLY.SUBQUEUE 

hmjeventjmbq EVENT.SUBOUEUE 

hmjnetajang CIO_META_TAG 

hmjconfig_addr^l the CIO slot of the DA (from ingr_hw_addrl) 



ZZI.4 Bind reply message 

The CAM should reply immediately to gpioO with a BIND_REPLY_MSG; this message tells gpioO if 
the bind was successful, and defines message-passing protocols. Fields examined by gpioO are: 

reply^tatus status of the binding 

Imjowj-eq^ubq low-priority request subqueue 



227.5 Do Bind reply message 

No matter what the reply_status, gpioO will send a DO_BIND_REPLY.MSG with good status to the 
I/O Configurator, on the subqueue saved from the do bind request. 

If the binding succeeded (the status of the bind reply is CI0^LVL1_CARD), gpioO will attempt to 
get its direct i/o pointer. If this attempt is successful, this instance of gpioO is now usable. 
Otherwise, this AH card cannnot be used. 



222 CAM Messages 

This section covers the messages gpioO uses to communicate with the CAM. The syntax of the CAM 
metalanguage can be found in Appendix 11; the semantics are covered in the HP-UX CIO Channel 
Adapter External Specification. 

A single transaction with the CAM consists of a request and reply pair. GpioO sends a 
CIO.DMAJO.REQ.MSG or a CIO.CTRL_REQ_MSG to the CAM to initiate some type of I/O 
or control transaction. 

When the request completes, the CAM completes gpioO's transaction by sending a 
CIOJ>MAJO.REPLY.MSG or aO.CTRL.REPLY31SG to gpioO. The reply status in the 
message will indicate bow the CAM perceived the transaction. 

At various times, the CA may detect an asynchronous condition on the API DA. GpioO will be 
notified via a CI0J0»EVENT3!SG. The I/O event will contain sufficient information to let gpioO 
know what event occurred. 



222/ CAM I/O Request/Repfy Message 

GpioO will use the aOJO.DMA.REQ.MSG to initiate I/O on the AH DA card. It will set the 
following fields: 

HP Confidential 5 



HP-UX CIO GPIO Monolith 



repfy^^bq REPLY_SUBQUEUE 
dajiumber the CIO slot of the AFI card 
vquadjchain pointer to the virtual quad chain 



The virtual quad chain generated by gpioO wll contain only one quad. The quad will be either a 
read or a write. 



2222 CAM Control Request/Reply Message 

GpioO uses the CIO^CTRL.REQ.MSG with the Ctrl June set to cither of the following CAM control 
requests: 

CIO^DA^SELFTEST Reset the DA and performance self-test; the CIO sense byte 

from the card will be returned in the ctrljnfo 
field of the control reply. 

CIO_GET_DIRECTJO_PTR Gel a pointer to the DA's I/O space; it is return- 
ed in the ctrLinfo field of the control reply. 



2225 CAM I/O Event Message 

A CIOJO.EVENT^MSG is sent to gpioO to inform it of an asynchronous event that occurred on 
the DA. The AFI card is only capable of producing the AES ARQ. Therefore, all events which are 
sent to gpioO are of this type. 

If the user was trying to catch ARQs, the user process will be signaled via psignal. Olherv^ise the 
event is dropped. 



223 Generic Messages 

Generic requests are used for powerfail and abort processing. 

ZZ3.1 Power on Request/Repfy Message 

The POWER_ON„REQ_MSG informs gpioO of system recovery from a power failure. On receipt 
of the poweron request, gpioO will immediately send a matching POWER_ON_REPLY_MSG to the 
CAM; this message will be sent on the lmJow^e<^ubq specified during configuration, in the 
CAM'S bind reply. 

The next step is to request a direct i/o pointer. The CIO_CTRL_REQ_MSG is used with the 
Ctrl June field set to CIO.GET^IRECTJO.PTR. Once the direct i/o pointer has been received, 
gpioO explicitly reset the 27114B and resets the software values associated with the hardware to 
powcrup configuration. 

If the direct i/o pointer is not received, this instance of the driver can no longer be used. 

The user process will be notified of power failure by receipt of the signal SIGPVVR, which is 
generated by the kernel. It is the user's responsibility to catch this signal and act upon it; by default, 
the signal is ignored. 
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12.3.2 Abort event message 

The ABORT.EVENT.MSG is used to abort an I/O request. GpioO will send an abort event to the 
CAM when a timed dma transaction does not complete before the timer pops. The CAM 
guarantees that eventually the original request will be returned. 
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3. M2uor Features Of The 271 14B Product 



64 word FIFO 

16 or 8 bit, user configurable mode of data transfer 

• 6 control lines (device defined/controlled) 

* 6 status lines (device defined/controUed) 

External interrupt line (allows the device to signal for attention) 

* Early termination to data transfers 

• Host end (allows the S800 to signal the device on the last transfer) 

• Optional GFIO-like mode of data transfer 

Locking of the interface (^ves exclusive access to the device) 

♦ 27114B to 27114B communication 

* Master and slave handshake modes 

* Read and write blocking (control returned to the user only after the 
last data word has been received by the device or channel) 
Multiple opens 

Locking of the interface for exclusive access 



Note: '*' denotes features that are new or extended to the API product as of Release 7.0. 



3.1 « word FIFO 

What makes the API card different from previous GPIO cards is the presence of an on-board FIFO 
coupled with the fact that the front and back planes of the 27114B operate independent of one 
another. It is because of the FIFO and the independently operating front and backplanes that the 
product can minimize the difference m the speeds between the S800 and the device. Although the 
FIFO is responsible for increasing the performance of the 27114B product, it is also responsible for 
increasing the complexity of what would otherwise be trivial read and write routmes. 



32 16 or 8 bit^ user configurable mode of data transfer 

The user can choose to send his data 16 bits at a time, a **word" in API terminology (hence the term 
"word mode"), or 8 bits at a time, a "byte" in API terminology (hence "byte mode"). The user's 
choice is dependent upon what the device can do. 

The 27114B always asserts 16 bits on the frontplane. If all 16 bits contain valid data, then the API 
product is functioning in word mode. If only Uie the lower 8 bits contam valid data, then the API 
product is functioning in byte mode. 

The 271 14B docs not perform the byte packing or unpacking. Nor does the API driver. Any byte 
packing/unpacking is done at the channel adapter level Hence, word and byte mode is really a 
function of the channel adapter, and therefore subject to the channel adapter's hardware Umitalions. 
Such limitations are: 

If the total number of bytes to be transferred is odd, or if the address given to the 
channel adapter is odd, the entire transfer takes place in byte mode - regardless of the 
driver setting. 
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This means any DMA transaction requested in byte mode is guaranteed to occur in byte mode. 
DMA transactions requested in word mode will occur m word mode as long as the total number of 
bytes to transfer and the address given is even. If either the number of bytes or the address is odd 
the channel adapter switchs to byte mode, resulting in only 8 bits of the 16 data bits being valid on 
the frontplane. 

Since the channel adapter has the ultimate say on word versus byte mode, it is important that the 
channel stay m agreement with the user and device expectations. One way to do this is for the AFI 
driver to protect the user from the channel adapter's limitations by failing word mode DMA requests 
in which the address or the number of bytes be odd. (Currently the driver only checks the total 
number of bytes) 

The driver relays the requested path width to the CAM via the ciojcmd field of the dma vquad. 



33 6 control lines 

There are up to 6 control lines available to the user. The user may assert any value on these lines. 
The value asserted has no meaning to the 27114B. The meaning is device dependent. 

The driver changes the control lines by writing to 6 bits (CTL[5] - CTL[0]) in one of the 27114B's 
memory mapped registers, register 7. Once set, they continue to assert that value until the next 
control line request (or the 27114B is reset). 

Although there are 6 physical lines (CTL5 - CTLO) on the frontplane that are used for the control 
lines, only four of these lines CTL3, CTL2, CTLl, and CTLO have dedicated outputs (CTL[3], 
CTL[2], CrL[l] and CTL[0] respectively). The other two lines, CTL5 and CTL4, are each 
multiplexed between two outputs. CTL5 is driven with output from either the CTL[5] bit or the DIR 
bit. CTL4 is driver with output from cither the CTL[4] bit or the HEND bit. (More on DIR and 
HEND later) 

WTiether the CTL5/CTL4 lines are driven with bits CTL(5]/CTL{4] or driven with the DIR/HEND 
circuitry, is user defmed. See the GPIO (DEV) manpage. 



3.4 6 status lines (device defined/controUed) 

There are up to 6 status lines available to the user. The device may assert any value on these lines. 
Like the control lines, the status lines have no meaning to the 27114B; only to the user and the 
device. 

The driver reads the status lines by reading 6 bits (STS[5] - STSfO]) in one of the 27114B's memory 
mapped repsters, regpbter 7. 

Although there are 6 physical lines (STS5 - STSO) on the frontplane that are used for status lines, 
only four of these lines STS3, STS2, STSl, and STSO have dedicated inputs (STSp], STSI2], STSfl] 
and STS{0| respectively). The other two lines, STS5 and STS4, are each multiplexed between two 
inputs. STS5 inputs to cither the STS[5] bit or the ATTN bit. STS4 inputs to cither the STS[4] bit 
or the PEND bit. (More on ATTN and PEND later) 

Whether the STS5/STS4 lines input to the STS151/STSI4) bits or input to the ATTN/PEND circuitry 
is user defined. If the user choses to see use the external interrupt feature, STS5 will input to the 
interrupt circuitry. 

Independent of the external interrupt feature, the user may choose to terminate data transfers early. 
In doing so, the STS4 line will no longer input to the STSI4] bit but to the drcuitry that controls 
early termination of data transfers. 
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3£ External Interrupt Line 

The external interrupt line (ATTN) provides a means by which the device can signal the user for 
attention. When this option is enabled and the external interrupt line is asserted by the device, the 
driver sends a signal, SIGEMT, to the process id that enabled the external interrupt option. To 
receive multiple signals, the user must enable this option after each signal is sent. 

To understand the external interrupt feature, the interrupt circuitry must be understood. When the 
device asserts the external interrupt line (ATTN) on the frontplane and the external interrupt feature 
is enabled, the 27114B'& ATTN flipflop is set. In addition, the 27114B's ARQ flipflop is set. It is the 
setting of its ARQ flipflop that causes the 27il4B to assert ARQ on the backplane. The setting of 
the ATTN flipflop is so the driver can know why ARQ was asserted (being that the 27114B has 3 
reasons for asserting ARQ: ATTN was asserted on the frontplane, PEND was asserted on the 
frontplane, or the transfer counter reached zero. More on PEND and the transfer counter later). 
This results in the API driver receiving a CIOJO_EVENT_MSG from the CAM where upon gpioO 
sends a SIGEMT to the process id. 

Once the ATTN flipflop is set, it will remain set until the driver resets it. However, the ARQ 
flipflop will be reset by the CAM after the 27114B responds to the ARQ poll. 

The CAM also disables the 271 14B from further assertions of ARQ^ why the user must enable the 
external interrupt after each signal is received. 

The 27114B Hardware ERS makes the statement that "ATTN is enabled when the card powers up". 
This can be misleading since is does not mean that the device can assert ATTN and the user receives 
a signal. It means that the ATTN flipflop is enabled (can be set). ^ But although ATTN flipflop can 
be set, the ATTN line does not input to the interrupt circuitry because at powerup time the ARQ 
flipflop is held reset. 

A more detailed description of what the driver needs to do for the external interrupt function is as 
follows: 

1. user makes ioctl request 

a) user wants external interrupts enabled. 

— save the process id of the current process 
-- save the process' interrupt handler. 

— enable the ATTN flipflop to register when ATTN is pulled. 

— enable the card to assert ARQ when the ARQ flipflop is set 

b) user disables external interrupts. 

— disable the card from pulling ARQ (hold the ARQ flipflop reset) 
~ throw out the process id 

— throw out the interrupt handler 

— dear the ATTN flipflop 



1. At one point in the AFl product cycle, the CAM re<«nabled the 27114 to assert ARQ after each ARQ occurred. 
However, it was found that the 27114 could prevent ^tem boot if the device asserts ATTN multiple tin»cs during 
configuration. Also, it is possible that system performance can degrade due to spurious interrupt messages. To prevent 
either of these side affects, it was decided Uiat the CAM would no longer re-enable ARQs on the 27114. 

2. This is necessary for backwards compatibility with the 271 14A. 
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2. ATTN was asserted on the frontplane - when the feature is enabled; The port server receives a 
CIOJO.EVENT.MSG and calls gpioO.event Jrom.camQ 

a) if the card is a 27114A 

— send a SIGEMT providing the pid saved and int.handler are valid 

— set the interrupt mask to reflect the cause of the interrupt 

b) if the card is a 27114B 

— send a SIGEMT providing the pid saved and int3andler are valid and providing the 
ATTN flipflop recorded ATTN was asserted 

— set the interrupt mask to reflect the cause of the interrupt 

— dear the ATTN flipflop 

Note: the driver must verify that the process id to which the SIGEMT is being sent saved is 
indeed still alive. Otherwise there is possibility that some other process may now occupy that 
slot in the process table and receive the signal. 

3. A GPIO_SIGNAL_MASK (lO.STATUS) call is made 

— return the interrupt mask (for API, always ST_ARQ2) in argfO] 

— clear the interrupt mask 



3.6 Early termination to data transfers 

This feature allows the device to signal the S800 that it (the device) has just received (or sent) the 
last data word. Hence, the device may chose to terminate any data transfer early by asserting PEND 
(Peripheral END) on the frontplane. This is useful when a user does not know how much data his 
device is sending or how much data his device is willing to receive. 

In the past, such applications found the AH product inflexible or unusable since the driver, wailing 
for the channel adapter to fulfill its transfer size, would eventually timeout. Since timing out is 
destructive to the 27114B and to the channel adapter (an abort message is sent to the CAM, which 
then resets the 27114B and the channel adapter), the result of the transfer is often incomplete data. 
With the addition of the PEND feature, the device now has a way to signal the chapoel adapter that 
it (the device) has just received or sent its last data word. 

The mechanics of PEND vary depending upon the direction of data transfer. For inbound 
transactions (data moving from device to channel adapter), the device asserts PEND when it asserts 
the last data word. At the assertion of PEND, the frontplane is disabled. The 27114B tracks the last 
word through the FIFO and asserts DEND (Device END) ^ on the backplane when that word 
CTOSses the backplane. For outbound transactions (data moving from channel adapter to device), the 
device asserts PEND as it performs its last handshake. The frontplane is disabled when FEND is 
asserted but this time the 27114B Immediately asserts DEND ^ on the backplane. 



Tlie assertion of PEND can also cause the 27114B to assert ARQ. This is an option that is available to the driver only. 
The mechanics of PEND causing an ARQ is best described in the write blocking context; be sure to read the section on 
write blocking. 

4. 

DEND need be asserted only if the channel is still involved in the transaction. 
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The assertion of DEND causes the channel adapter to stop receiving or sending data on the CIO bus 
- regardless of its count. The channel is therefore free to non-destructively finish the transaction and 
the CAM is able to send a DMA reply message to the waiting driver. 

The use of FEND has some interesting effects on the 27114B's FIFO. The effects vary depending 
upon the direction of data transfer. To understand the effects, the movement of data through the 
FIFO must be understood. 

For inbound transactions, the data is moving from the device, across the frontplane, into the front of 
the FIFO, through the FIFO and aaoss the backplane into the channel When a device signals that 
it has sent its last data word, that word must travel the entire length of the data path before reaching 
its destination. When it reaches the backplane DEND asserts. The transaction completes only after 
the channel receives the word. The result is an empty FIFO. 

For outbound transactions, the data is moving from the channel, across the backplane, into the back 
of the FIFO, through the FIFO and across the frontplane. At some arbitrary time, as data continues 
to spill into the back of the FIFO, the device asserts FEND and stops handshaking. The last data 
word has already reached its end destination; no other data movement occurs. The FIFO may or 
may not contain data (any remaining data is considered garbage). 

Because data may be left over, the driver should clear the FIFO after write transactions that end 
with a FEND. 

Note: If the transfer counter is not enabled, the driver will be unable to figure the residue value ai 
the end of the transaction. Instead the driver relies upon the CAM to figure the residue. Since the 
channel's responsibility ends at the backplane, the CAM's residue value may be off (too small) by as 
much as 64 for outbound transactions. 



3.7 Host END (HEND) 

The Host End feature allows the S800 to signal the device on the last transfer. This is similar in 
concept to the FEND feature. It consists of the 27114B forwarding the backplane signal CENT) 
(Channel END) onto the frontplane as HEND. 

Once HEND asserts, the driver must force the dcassertion of HEND. The method of deassertion 
depends on the direction of data transfer. If the HEND occurs on an outbound transaction, the 
driver must clear the FIFO and load the counter with a non-logical zero value before HEND will 
deassert on the frontplane. If the HEND occurs on a inbound transaction, the driver must load the 
counter with a value other than logical zero (greater than OxFFFF) before HEND will deassert on 
the frontplane. 



3.8 Optional Transfer Counter 

The transfer counter was added to the AFI product to resolve two problems: 

• The 27114A can not work in a true GFIO environment. Because of this, data can be lost. 

• The driver can not know, in a reasonable manner, how much data exists on the 27ll4A's FIFO. 
Because of this, the driver can oot successfully block write transactions or report accurate 
residues. 

The fust problem is better understood with a bit of history. 

One of the features of the 27114A card, referred to as read pre-fetch, means the 27114A, 
when configured to read, will continue to ask for data as long as its FIFO is empty. 
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Once the FIFO fills, the 27114A breaks the handshake. 

This implies that after the channel has received the requested amount of data, there is 
room on the card for a FIFO full of "extra" data. Should the device continues to make 
data available, the 27114A will continue to handshake up to a FIFO full of data 
independent of the channel and the driver. The handshake is stopped by either the 
27114A (when the FIFO fills) or the device (when it has no more data). 

This pre-fetching on read transactions, when followed by another read is valuable; most 
of the time. Unfortunately, HP failed to anticipate the various environments that the 
AFI product would be sold into. Some applications are time sensitive to the degree that 
the leftover data is no longer valid and can not be used. Some applications do more than 
read from the AFI produrt. Specifically, should the next transaction be a write, the extra 
data must be removed from the FIFO. Otherwise it is written back to the device. But 
can that data be thrown away, and if not, what should be done with that data? 

Two points should be gleaned from this history. 

1. The driver is incapable of making those decisions. Even if it were capable, the decision could 
not be made in a timely manner. 

2. The 27114A product only works in environments where the AFI product is only asked to read 
or/and where the device knows exactly how much data it should send (thereby avoiding the 
pre-fetching). In all other environments, the product could not be successful. 

In an effort to resolve customer problems and expand the number of enviroimients in which the AFI 
product can function, a physical counter was put on the card. At the user's request, the driver 
enables the counter and initializes it to clock the appropriate number of transfers. The counter 
clocks the number of transfers across the ifrantplane. Once the correct amount of data is 
transferred, the frontplane is disabled. So by dboosmg to use the counter, the user can prevent the 
read pre-fetch (and all of the "problems" associated with read pre-fetch). 

The mecham'cs of the counter are simple. The driver enables or disables the counter based upon 
user request. This is done by touching a bit in register B. If enabled, the driver loads the counter 
before sending the CIO_DMA_REQ_MSG to the CAM. Loading the coimter is a two step process 
since the counter has two parts. The correct value must first be written to the counter's write 
register (via the direct io pointer) and then the part of the counter that does the actual countmg 
must be loaded with that value (toggle the counter's load bit via the direct io pointer). The counting 
portion of the counter will then decrement toward z&wmih each word that aosses the frontplane. 

The counter, for hardware reasons, is a bit strange. It, in effect, considers zero to be OxOOFFFF. 
Hence the value loaded into the counter must have an offset of OxOOFFFF. This is explained in the 
27114B Hardware ERS. 

Since the transfer counter decrements with each front plane transfer, and the number of valid bytes 
aossing the front plane with each tranter depends upon the width of the data path, the value loaded 
into the counter is a function of the data path width. When in word mode each transfer aossing the 
frontplane consists of two data bytes. Hence the conntei must be loaded with a value that is half the 
users requested number of bytes. 

The second of the two problems that the transfer counter resolves is: 

The driver can not know, is a reasonable manner, how much data exists on the 
27114A's FIFO. Because of this, the driver can not report accurate residues. 

There are actually three factors contributing to this problem. 

1. The 271 14A has no reasonable way i^ kncwving how much data is in its FIFO. 
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2. The channel adapter's responsibility to a write transaction ends once the last data word moves 
from the bus onto the 27114A/B. 

3. Outbound transactions are not complete until the last data word has been received by the 
device. 

Because the driver and the 27114A could not figure out how much data was in the FIFO, the CAM's 
residue value had to be used. There is a slight problem with using the CAM's residue value: 
Although the channel will report that all data has been successfully sent, in reality, up to 64 words of 
data may still exist in the FIFO. Hence the CAM's residue value may be off (too small) by as much 
as 64 words for outbound transactions. 

With the addition of the transfer counter to the AFT product, the driver can now report an accurate 
residue by reading the counter.* 

For read transactions, the amount of data received by the channel will be accurate; the counter need 
not be looked at. 

Yet another benefit of the transfer counter is that the driver has the option of configuring the 
271 14B to assert ARQ when the counter reaches logical zero. Why the driver would want to do this 
is best described within the context of write blocking; be sure to read the section on write blocking. 



3.9 Read and write blocking 

In the context of this discussion, read blocking refers to the driver not completing the transaction 
until it is sure the last data word has been received by the channel; write blocking refers to the driver 
not completing the transaction until it is sure the last data word has been received by the device. 

Without read/write blocking, the user might make a request of the driver that is destructive to the 
data path while data is still enroute. This was a problem for the 27n4A product (with write 
transactions) since the driver, not knowing how much data existed in the 27114A's FIFO, did not 
know when to declare the transaction complete. 

Read blocking is trivial, from the driver's point of view because the data must travel to the channel 
before the channel can finish, return the CAM and the driver receive a DMA reply message. In this 
case, the receipt of the DMA reply message guarantees the requested amount of data has left the 
device and arrived on the channel. 

Write blo^dng is not so trivial, because the last data word only has to leave the channel (not the 
card) before the channel, being satisfied, returns to the CAM and the driver receives the DMA reply 
message. The DMA reply message docs not guarantee the data has traveled from the channel to the 
device. It only guarantees that the data has traveled from the channel to the 27114B. 

Write blocking relies upon the transfer counter. If the transfer counter is not enabled, then the 
driver can not write block (it behaves like the 27114A product). It was decided that having the 
27114B pull ARQ every time the last data word crossed the frontplane to the device, was too 
expensive.^ It was also decided that having the driver poll the counter until it registered a zero value 



Note: beoiuse of the way the counter docks data, it is possible that tfse eouater will read zero (OxOOFFFF) when in fact the 
last data word has not yet traosferred. The drivtr can circumvent this problem by looking to see if PCTL is high 
(indicating the device has not yet acknowledged the movement of the last data word) and adding one to the transfer 
counter if it is. 

6. 

The expectation exists that the vast majority of the time the device will be fiister than the time required for the channel to 
return to the CAM, for the CAM to build and send a DMA reply message, and for the drivtr to be invoked. 
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was too expensive. The decision was made to have the driver read the counter once. If the counter 
was zero, great. Otherwise the driver should enable the 27114B to puU ARQ, when the counter did 
arrive at logical zero, and wait for a CIOJO.EVENT^MSG. When the event message did arrive, 
the driver should check the interrupt flipflops to detcrmme the cause of the ARQ (ATTN or the 
transfer counter going to logical zero). 

To throw a wrench m an already sticky situation, imagine the case where the counter is enabled, and 
the PEND option (ability to terminate data transfers early) is enabled. Now imagine a write taking 
place with a device that is slow (the driver receives its DMA reply message before the last data word 
is gone). The counter, when checked, is non zero. The driver correctly enables the 27114B to ARQ 
when the counter reaches zero. But, before the last data word crosses the frontplane, PEND is 
asserted on the frontplane. The counter will never reach zero, the driver will continue to wait for an 
ARQ until the transaction times out; the driver will incorrectly abort the transaction and return an 
error to the user. 

To prevent this situation, the driver has the option of enabling the 271 14B to assert ARQ when 
PEND is asserted on the frontplane. So in the above situation, the CIO_IO_EVENT_MSG alerts 
the driver to check the three interrupt flipflops to determine the cause of the ARQ (ATTN, the 
transfer counter going to zero, or the assertion of PEND). Upon seeing the cause is PEND, the 
DMA transaction can be completed. 

Once the PEND flipflop is set, it v^iil remain set until the driver resets it. However, the ARQ 
flipflop will be reset by the CAM after its ARQ poll. 

Once the transfer counter-has-reached-zero flipflop^ is set, it will remain set until the counter is 
non-zero. This means the driver must either load the counter with a non-zero value, or it must reset 
the counter. 



3.10 Master and slave handshake modes 

There are three handshakes possible, full master, full slave and fifo master. Fifo master is the same 
handshake used by the 27114A (the 27114A has only one handshake). 

The only thing the driver needs do for the handshake modes is correctly set the bits in register B to 
indicate the handshake requested by the user. 



3.11 27114B to 27114B communication 

The driver need do nothing for B to B communication, which is all a function of hardware.* The user 
is responsible for making the driver requests to set one card as master of the handshake and one 
card as slave of the handshake. ^ 



3.12 Multiple opens 

As of Release 3.0, an AH driver can have more than one open fde descriptor, up to 16, at any given 
time.' With multiple accesses to the driver came the concept of per-interface driver attributes and 



7. It K really a bit; not a flipflop. 

8. The 27114A docs not support 27114A-to-27114A links. 

9. There is nothing significant about the numt>er 16; it wis grabbed out of the air. 
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per-open driver attributes. Per-btcrfacc attributes are those attributes that effect all file descriptors 
for a given card. Typically this means options that are configured in hardware, such as data width. 
Per-open attributes are those attributes that effect only one file descriptor. Typically this means 
attributes that are configured solely within software, such as timeout value. 

There are three per-open attributes: timeout, signal mask and lock count. The remaining options are 
are considered per-interface attributes. 

If each timeout is associated with an open, the driver needs to know which open's timeout to 
reference. But the file descriptor alone is not sufficient in distinguishing one open from another, as 
the same file descriptor may be opened many timeSo 

What the driver does, is to create a pseudo minor number, based upon the actual minor number, 
that is unique to that open. The pseudo minor number is then passed back to the high level open 
routine. Recall that the minor number format for gpioO is 



(Ibit) 


Obits) 


(4bits) 


(8blts) 


(Sbits) 


D 


not^used 


pseudo 


lu_number 


not^used 



By altering one of the four pseudo bits of the mmor number, the driver can uniquely identify up to 
16 opens.^° 

The kernel maintains the mapping between that open and the pseudo minor number. Every request 
made to the driver from that open, results in the kernel passing the driver the appropriate pseudo 
minor number. 

The driver maintains the per-open attributes in its pda, in the following structure: 

struct per.open.entry { 

unsigned timeout; /* device timeout in u-seconds ♦/ 

struct proc *int_Jiaiidler; /* interrupt handler process ♦/ 

short int_handler_pid; /♦ pid owning the interrupt handler */ 

int po_lock_ct; /* lock count lor an open ♦/ 

struct per. open. entry ♦link; /♦ ptr to next available per_open.entry */ 
>: 

struct per.open.entry potCMAX.OPEBS] ; /♦ Per-Open Table ♦/ 

struct per«open_entry »pot.head; /* pointer to next available entry ♦/ 

struct per_open.entry *pot_«nd; /♦ pointer to last available entry */ 

The pointer, potjiead (Per Open Table Head), marks the first unused entry and the other, potjend 
(Per Open Table End), marks the last unused entry. All unused/available entries arc linked 
together, via link 

As opens occur, the driver takes the first avadlable entry in the array (as indicated by potjiead), 
initializes the values, advances potjiead, destroys link and creates a pseudo minor number. The 
challenge in aeating the pseudo minor number is that the driver must relate the minor number to 
one of the appropriate index of the pot array. The driver does this by assigning the pot array index 
of the just initialized entry to bits 19 through 16 of the minor number. 



10. 

The pseudo minor number is not represented as an actual device file; it is known only to the kernel. 



16 HP Confidentiil 



HP-UX CIO GPIO MonoUlh 



As closes occur, the driver links the now-defunct entry to the end of the free list (as indicated by 
pot^end). 



3.13 Locking 

By locking the AFI interface, a process gains exclusive access to the device. Other processes' 
requests will wait until either the locking process unlocks the interface or the time for their requests 
expire. (However, the request will immediately return mth an appropriate error, if the 0_NDELAY 
file status flag is set.) 

Note that the locking gives exclusive access to the device; not to the interface. Since some attributes 
(per-open) have no relation to the hardware/device, they have no effect on another process. 
Therefore the driver allows requests that deal with per-open attributes, regardless of locks. 

The driver maintains two types of lock counts, 

• the number of locks per a given interface 

• the number of locks requested per a ^ven open. 

Each time the locking process requests a LOCFLINTERFACE, the interface lock count (and the 
appropriate per-open lock count) increments by one. Each time the locking process requests an 
UNLOCK_INTERFACE, the interface lock count (and the appropriate per-open lock count) 
decrements by one. When the locking process requests a CLEAR_ALL_LOCKS, the interface lock 
count (and all per-open lock coimts) resets to zero. 

When a process locks the interface, the driver saves that process' pid and marks the interface locked. 
Any request to change the per-interface attributes (GPIO.WIDTH, GPIO.CTL.LINES, 
GPIOJIGNAL^MASK, GPIO.RESET, GPIO.LOCK, GPIO.SET.CONHG) must then come 
from a process with a pid that matches the saved pid. 

The locking process should remove all locks before exiting. The driver attempts to remove locks for 
the process that exits before it removes its locks. The driver's only indication that a process has 
exited is when the driver close routine is called. So cleaning up of locks is done in the close routine. 
However the driver close routme is called by the kernel only when the last close on a file descriptor 
is made. This means a process which locks the interface, forks, and exits ^thout removing its lock 
wiU continue to prevent access to the interface until the child process exits (causing the last close on 
the shared file descriptor). 
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4. Data Structures 

The data structures for gpioO can be divided into three main groups: locak, external, and the port 
data area. Interesting locals are explained in the sections for the various routines. 

Externals are those variables which are global to the entire kernel. All externals for gpioO are 
declared in the file machine/space.h. External variables are dangerous to use because all instances 
of gpioO use the same copy of these variables. Therefore, exclusive access to externals must be 
enforced. 

Fortunately, gpioO docs not require may externals. The first external, num^ioO, indicates how 
many instances of gpioO exist in the system; that is how many times gpioO was included in the 
configuration file. This variable is used only on opens. The open routine uses the variable to ensure 
that non-existent lu's are not used. 

The second external, gpioOjtdajnap, is an array of pointers to port data areas. This array is 
initialized by gpioO during configuration. One element of gpioO_pda_map is used for each instance 
of gpioO; that is, the size of gpioO_pda_map is num_gpioO. The array is used by the LDM routines 
to match lu's with port data areas. The macro PDA_MAP takes an lu number and returns a pointer 
to the corresponding port data area. 

The port data area (pda) is the other large data structure which gpioO uses. Each instance of gpioO 
has its own pda. As explained above, the LDM routines can get access to the appropriate pda via 
the macro PDA_MAP. The port server is invoked with the pda as one of its arguments. 

Elements of the pda also need to be protected from simultaneous access. In this case, access can 
occur from the LDM routines and the port server at the same time. Therefore, if a variable of the 
pda is used from both sides, it may need to be protected via semaphoring. 



/• pda: Port Data Area •/ 



state 



io_state 



old^card 

lu 

diag_port 

msg_id 

ctrLmsg_id 



State of the manager: configuration (GET_DIO_PTR), powerfail 
(PF_GET_D10_PTR), or normal (lO.REQ.READY) 

State of manager (specific to DMA). There are 3 logical states: 
ready for io (read or write), doing io (read or write), and wailing. 
for data to leave the card (write). But only 2 that the driver cares 
about; waiting for data to leave the card (WAITNG.ONJNTR, 
and not waiting for data to leave the card (lO^RECLREADY). If 
the io^state is WArnNG_ON.INTR, the driver has received the 
DMA reply msg. So it is important to know that when the 
transaction times out, sending an abort msg to the CAM (the usual 
action for a timeout) does nothing. Instead the driver should dean 
up and return to the user. 

27114A or 27114B ? 

Logical unit number 

Flag to tag a diagnostic port 

Message id of last request 

Message id of last Ctrl req 
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msg_id_from_above 

pf_trans_num 
shadow? 

shadowB 
Reg_H 
next_msg_id 
trans.num 

timerjd 

req_state 
wait_siatus 

flags 
localmsg 



buf 
vquad 

*dodio_ptr 
rcsetbuf 



Used in configuration. Is the msg id of the do.bind.req received 
from the Configurator. The same msg id needs be used in my 
do.bind.rcply. 

Transaction number from the most current powerfail message 

A 'shadow register' is a software copy of a write-only register. 
They are important method in knowing which bits are set. 

For register B (AH Control II Reg) 

27114B reg that holds the upper byte of the transfer counter. 

Message id for next request 

Transaction number of current req. Get this from lO Services, 
during configuration. Since can only do one transaction at a time, 
use this same number each time 

A timer is needed to clock each transaction. The same timer is 
used over and over. io_^et_timer call is made during 
configuration. 

Need to know which direction the previous DMA transaction went, 
so the driver knows how to treat the FIFO. 

Used in gpioO_wait.on_lock. The value returned indicates whether 
the the current user request can continue or must fail because the 
interface is still locked. 

Reflects various user options that need to be tracked: 
OLD.CARD, CTR_EN, FEND.EN, 

WORD_MODE,INTERUPT.EN, BUSI, WANTED, RST^USI, 
RST.WANTED, HDWR.DEAD. 

The msg used to send requests to the CAM. Note that once 
configuration is complete, it is used for only 3 types of msg 
requests: dma, control and abort events. Therefore only the msg 
descriptor field and the vquad pointer (or control function) need 
be changed on each request 

Buffer structure (buf.h) used by read and write to do dma 

The single virtual quad which gpioO uses to initiate dma. Only the 
command, count, and address fields change on each request. The 
link, residue and address class fields are always zero. 

The pointer to the direct i/o space for the card which this gpioO 
controls. Used to poke and read registers on the AFI card 

Used for multiple resets 
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*req_process Process making dma request; need to periodically check whether it 

has been killed. 

/* ioctl returns */ 

int_mask Hold the reason the card pulled ARQ 

interface^type Interface id from cards id re^ster 

usecsjeft Miaoseconds left in timeout 

tcrm_reason Reason for last termination (not used) 

ctl User defined mask to write to the control lines 

hndshk Handshake mode 

edg Which edge of PFLAG latches data? 

config_mask Used for io_env calls. Reflects the configuration of the card's hw 

/* Buffer space */ 

b_data3ufI3 + CPUJOLINE] 

*b_data Pointer to cache-aligned data 

b_data_dpt Dpt of same 

/* config data */ 

hw_addr_l Address of our hardware 
config_port Configurator port number 
my.port Port number for API manager 

cam^port Port number for the CAM 
cam_subq Subqueue of cam to send msgs to 
buffer_16 A 16-bit buffer for Ctrl replies 

/* for iolock/unlock ♦/ 
pot[MAX_OPENS] Table of pcr-opcn variables 
*pot_head Pointer to next available entry 

•pot^end Pointer to last available entry 

locker Process that has the interface locked 
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pUock_ct Lock count for the interface 

/* Table ofper-open values */ 

timeout Device timeout in u-seconds 

•int^handler Interrupt handler process 

int_handler_pid Process id owning the interrupt handler 

pojock^ct Lock count for an open 

•link Pointer to next available per_open_entry 

Below are the remainder of defines and types declared in gpioO^spc.h: 



typedef struct { 

llio_std„header.type 

union { 

creation.info_type 

do3ind.req_type 

do_bind_reply_type 

bind_req_type 

bind„reply«type 

cio_dma_req_type 

cio_dmo^reply_type 

cioJo_event_type 

cio_ctrLreq_type 

cio.ctrLreply_type 

}u; 
} gpioO^msg^type; 



The message types gpioO understands 



msg^header; 

crcation_info; 

do_bind_req; 

do.bmd^rcply; 

bind^req; 

bind.reply; 

do_dma_req; 

do.dma^reply; 

doJo_cvent; 

do^ctrLreq; 

do.ctrLreply; 



Drivers breakdown of its miyor/minor number - for multiple open support 



typedef union { 
struct { 

unsigned gp.major :8; 

unsigned gp.diag :1; 

unsigned gp.unusedl '3; 

unsigned gp.pseudo :4; 

unsigned gp Ju :8; 

unsigned gp unused2 :8; 
}GP; 
int ail; 
} gpioO.dev; 



Defines for ease of use 
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# define g_major 

# define g^diag 

# define g_unusedl 
#define g_pseudo 

# define g_lu 
#define g.unused2 



# define Reg^l 

# define Reg_3 

# define Reg_7 
#define Reg>9 

# define Reg_A 
#define Reg_B 



/* ...related to de\'ice number (for multiple opens) */ 

GP.gp.major 

GP.gp_diag 

GP.gp_unusedl 

GP.gp«pscudo 

GP.gpJu 

GP.gp_uniised2 

/* ...related to the direct i/o pointer (from the pda) */ 

ciodio_ptr-5> ^Isens.noniial 
dodio.ptr- > ctlsens.ccnd 
ciodio_ptr-> ctlsens-ccndbyte 
ciodio«ptr->statcmd.nonnal 
dodio_ptr-> order.cend 
ciodio_ptr->statcmd.cend 



/' 



# define 

# define 

# define 

# define 

# define 

# define 
#define 

# define 

# define 

# define 



HDWTl_DEAD 

BUSI 

WANTED 

WORD.MODE 

OLD^ARD 

CTR_EN 

PEND_EN 

RST3USI 

RST^WANTED 

INTERUPTEN 



Dennition of the bits in pda->flag */ 

ELEMENT.OF32(0) True if bdw off-line, etc. 

ELEMENT_OF.32(l) Someone's using the card 

ELEMENT_OF_32(2) Someone wants the card 

ELEMENT.OF.32(3) Word/byte mode flag 

ELEMENT.OF.32(5) Can the user do 271 14B features? 

ELEMENT_OF_32(6) Easier to keep a flag than read the 

ELEMENT_OF_32(7) Hw each time gpioO needs to know 

ELEMENT_OF_32(8) A reset is in progress 

ELEMENT„OF_32(9) Someone wants to do a reset 

ELEMENT_OF.32(10) ATTN-arqs are enabled 



#defme MAX_OPENS 
#defme END_OF.TABLE 
#defme REVO 
#defme REVl 
#defme LOGICAL^ZERO 



Miscellaneous dermitions 



V 



The maximum times the device file can be opened 



16 
-1 

0x0 The 27114A can only have a revision number equal to or 1 

0x0100 

OxFFFF 
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/• Register layouts of the 271 14B •/ 



#defme DJNT_D 


0x4000 


#define CJNT.D 


0x2000 


#defme LDCTR 


0x0800 


#defme CL5 


0x0400 


#defme CL4 


0x0200 


#defme CU 


0x0100 


#defme PRN 


0x0080 


#defme DIR 


0x0040 


#defme EDGE 


0x0020 


#derine CLF 


0x0010 


#derme PEN 


0x0008 


#derine CL2 


0x0004 


#derme CLl 


0x0002 


#derine CLO 


0x0001 




/• 


#defme PEND.FF 


0x2000 


#defme ATTN.FF 


0x1000 


#define CTR_Fh 


0x0800 


#derme ST5 


0x0400 


#derme ST4 


0x0200 


#define ST3 


0x0100 


#defme PCL 


0x80 


#derme PFG 


0x40 


# define OR 


0x20 


#defme IR 


0x10 


#defme TES 


0x08 


#derme ST2 


0x04 


# define STl 


0x02 


#define STO 


0x01 




/* .. 


#define ATTN.EN 


0x0080 


#define PDIR.EN 


0x0040 


#define CI R.RST 


0x0020 


#defme PEND.RST 


0x0010 


#defme FIFOM 


0x0007 


#defme FULLM 


0x0006 


#defmeFUl.LS 


0x0004 



,..27114 Control Re^ster Layout */ 
DEND interrupt disable bit, 27114B 
Hdshk.ctr=0 intrpt disable bit, 27114B 
Load ctr bit, 27114B only 
Control bit #6, 27114B only 
Control bit #5, 271 14B only 
Control bit #4, 27114B only 
Poll Response Enable 
direction for data transfer 
Edge determination for data movement 
Clear FIFO 

Enable frontplane's response to handshake 
These three bits are 
used to write information 
to the control lines 

...27114 Status Repster Layout */ 
Flip-flop indicating PEND was pulled 
Flip-flop indicating ATTN was pulled 
Flip-flop indicating the hndshk ctr^O 
Status line #6, 27114B only 
Status line #5, 271 14B only 
Status line #4, 271 14B only 
Peripheral Control 
Peripheral Flag 
Output Ready 
Input Ready 
Test Hood Present 
These bits return the state of the 
status lines being driven by the 
peripheral. 

,271 J4B Control 11 register layout */ 
Enable ATTN to cause ARQs 
CTL5 line driven by CTL5 bit or PDIR? 
Enable/disable(reset) the ctr ARQ flipflop 
Enable/disable(reset) the DEND ARQ flipflop 
Reserved for handshake mode definition 
Used for handshake mode definition 
Used for handshake mode definition 



HP Confidential 



23 



HP-UX CIO GPIO Monolith 



5. Outline Of Driver 

GpioO is organized as a monolith; that is, gpioO includes both an LDM and a DAM. This 
organization is very advantageous for both speed and £X>de aze. As a monolith, gpioO can be divided 
into two broad areas: the LDM routines and the port server routbes. 

The LDM routbes include all of the standard HP-UX entry points. These routmes are explained in 
the LDM chapter. 

The port server consists of the port server itself and each of the routines it calls to process a 
particular t)^ of message. The port server itself is just a switch statement with a separate case for 
each message type. Each message type which gpioO can receive is processed by a separate routine. 
In general, these routines are invoked with a pointer to the incoming message and a pointer to the 
pda. 



5.1 LDM Routines 
5.1.1 Useful Macros 

A few macros are used by the LDM routines. Every routine uses the macro PDAJ4AP which takes 
a dev_t and returns the pda which corresponds to that device. It does so by examining the 
gpioO_pda_map array which is built during configuration. 

Two other macros, LU and GPI0_D1AG, are only used by the gpioO.open routine. LU returns the 
logical unit number of the device when given the devj. GPIO.DIAG returns true if the devj 
passed in is for a diagnostic open. 



5.12 Direct I/O 

All device adapters connected to the channel have a set of memory mapped registers called the 
direct i/o space. The Driver Writer's Manual explains direct i/o in the chapter on the CAM 
interface. 

GpioO uses direct i/o to read status from the card and to initiate dma and do control requests to the 
card (via ioctl calls). The direct i/o pointer (ciodio_ptr) is grabbed via a CAM control request 
during configuration. Thereafter, to examine or poke a re^ster on the AFI card, gpioO just 
references the appropriate offset from dodio.ptr. A list of registers used follows: 



Register R/W Structure Element 



Usage 






Read 


dodio«ptr-> data.DormaI 


1 


Read 


dodio.ptr-> ctlsens Jiormal 


3 


Read 


dodio«ptr-> ctlsens.cend 


7 


Read 


dodio^ptr- > ctlsens.ccndbyte 


9 


Read 


dodio.ptr->statcmd.normal 


A 


Read 


dodio_ptr->order.cend 


B 


Read 


dodio.ptr-> statcmd.cend 





Write 


dodio^ptr- > data.norm al 


1 


Write 


dodio_ptr-> ctlsens.normal 


7 


Write 


dodio^ptr- > ctlsens.cendbyte 


A 


Write 


dodio_ptr- > order .cend 


B 


Write 


dodio_ptr-> statcmd.cend 



data register 
CIO sense register 
ID renter 
27114 status register 
CIO status register 
transfer counter 
transfer counter 

data register 

CIO control register 

27114 control register 

transfer counter 

transfer counter and 27114 control II register 
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5.13 gpioO_open() 

GpioO.open is the routine by which a user process gains access to the driver. If an error is returned 
from tliis routine, the user can not proceed with other requests to the driver. 

Several types of checking must be done. If the driver is not configured (pda is NULL) or the 
hardware is bad/missing (pda'> flags contain HDWR«DEAD), then the open should fail. Also, if 
the lu of the device file being opened is bc^s for one reason or another (the lu was not configured, 
or has improper format) the open should fail. 

Beyond the error checking, the goals of the open routine are to, create a pseudo minor number for 
the open in progress (multiple open feature), and initialize those options that are unique to that 
open (the timeout, the interrupt handler, the pid of the interrupt handler, and the per_open lock 
count). 

If the open is a diagnostic open, lock the interface (don't forget to increment the interface and per- 
open lock counts) and drop other locks (don't forget to grab the process id). Only one diagnostic 
open at a time is allowed. 



5.1.4 gpioO_closc() 

The routme closeQ is called by the user process to relinquish access to the device. However, 
gpioO.dose is called by HP-UX only on the last close made to the device file. 

The goals of the close routine are to, remove any locks that belong to this instance of open, add the 
now-free per-open entry to the end of the pot table, and clear the interrupt handler associated with 
the close so that the process won't be signaled on an interrupt after it (the process) has terminated. 

Note: the driver has no responsibility for the device. 



5.13 gpio.busyO and gpio_free() 

These routines are used to guarantee exclusive access to the device. Before a request is started, 
gpio^busy is called. After the request has fmished, gpio^free is called. 

Gpio.busy is simply the exclusive access portion of physio(). It sleeps on buf until buf is available. 
Once it becomes available, gpio_busy sets the B_BUSY flag. Of course, all of the above is done at 
spl5 since it is a critical section. 

Gpio^free simply marks bufa& not BJBUSY and does a biodone to release the semaphore. 

Note that only gpioOJoctl must use these routines. Semaphoring, in this manner, of the read and 
write requests is done for free by physioQ- 



5.1.6 gpio0.set.ti]iieout() and ^ioOjservke.timeoutO 

These two routines are used to provide a watchdog timer for dma requests which are sent to the 
CAM. GpioO_set.tianeout is caBed r%ht before the iojiendQ to the CAM for the dma request. 
When the dma reply is received from the CAM, the timer is released. Gpio0^ervice_timeout will be 
called from softdodc if the dma request has not finished in the allotted time. 

The allotted time for a dma request is initially set at one hour and can be changed by the user via 
the ioctl GPIO.TIMEOUT. The full timeout value is further broken down into smaller chunks 
called GPIOTAs (2 seconds each). This is done so that a process with outstanding i/o can be killed 
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fairly quickly by the user instead of waiting for the full timeout. 

GpioO_set_timeout calls the timeout routine with a time limit of GPIOTA (or whatever is left in the 
full timer, if less). It sets up gpioO_scrvice.timeout as the routine to call if the timer pops. 

GpioO^ervice^timeout is called whenever the timer pops. If time stiU remains, the time limit is 
decremented and timeout is called again. If no time remains in the full timer or if the user has 
killed the process, an abort message is sent to the CAM, providing the request is still active at the 
channel level. This guarantees that the request will complete in the near future. If the request is no 
longer active at the ehasnel level (indicated by a req_state set to WAITING^ON^INTR), the driver 
is waiting for data to leave the card; an abort message is not necessary as the reply message to the 
request has already been received. The driver needs only clean up after the dma. 



5.1.7 gpioO_write() and gpioO_read() 

These routines are used to write (or read) to (or from) the device. They are identical to each other 
except for the direction of data transfer. 

physioO is called to lock down buffers and do the rest of it's voodoo. Included in this voodoo is the 
call to gpioO^strateg}' and the sleep on buf. Finally, when the associated biodone is done after a dma 
reply is received, control is passed back to gpioO_write (or gpioO^read). Note that physio() provides 
a semaphoring mechanism for access to the card. No other write (or read) can go through until this 
one finishes since physio() has grabbed buf. The ioctl routine makes use of this fact and uses 
gpioO_busy to sleep on buf. 

These routines are intentionally structured so that all of the real work is done cither in physio() or 
in gpioO.strategy. 

So, the goals of the write routine are to, 

— Block writes (reads) from processes that do not own the lock [if one exists], 

-- Refuse word mode writes (reads) that are transferring an odd number of bytes,, 

— Block other writes (reads) if one is currently in progress, 

— Call physioQ, 

— Free the driver and wake up any processes waiting to write (read), 

— Return appropriate write (read) errors 



5.1.8 gpioO^strategyO 

Gpio0.strategy does all the real work for i/o requests. It pokes registers on the AFI card to 
configure the transfer (direction of the dma, transfer counter, PEND) and sends the dma request to 
the CAM. The routme consists of three basic cases. 

First, if this is a diagnostic request, no register poking will be done. The diagnostic program is 
required to do this itself. GpioO_strategy only marks REQ^STATE as UNKNOWN and sets up the 
VQUAD command for either a read or a iimte. 

Second, if this request is a write, a few register pokes are done and the VQUAD command is set up 
for a write. Note that registers must be poked in different ways depending on whether the last 
request done was a write or a read, and depending on whether the transfer counter or PEND are 
used. See the 27114B Hardware £RS for details on which registers to touch and how to touch 
them. 
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Third, if this request is a read, some other register pokes are done and the VQUAD command is set 
up for a read. 

Finally, the common parts of the vquad are set up (count and buffer). A watchdog timer is started 
via gpioO„set_timeout. The dma request message is sent to the CAM via io_send(). 

Note the precautions for powerfail, io.Wock^scrverQ and io^unblock^serverQ. 



5.1.9 gpioO_ioctl() 

GpioOJoctl is the grab bag for all other types of requests to the device. There are three basic types 
of requests: lO.CONTROL, IO_STATUS, and I031>rVIR0NMENT. Most of these requests are 
simple writes or reads to one or more of the CIO direct i/o registers. The exception is 
GPIO^RESET which does a CIO.DA_SELFTEST control request to the CAM. 

The body of gpioOJoctlQ is bracketed by gpioO.busy and gpioO.frce to semaphore access to the 
card; and access to the interface is refused if the interface is locked by another process. If the 
interface is not locked or is locked by the current process the request is handled as follows, 

5.19.1 GPJOJ.OCK 

IO_CONTROL Handle LOCKJNTERFACE, UNLOCKJNTERFAGE and 

CLEAR_Al-L_LOCKS commands. After each successful lock or unlock 
request, the number of locks for that open is returned in arg[l] and the 
number of locks for that interface is returned in arg[2]. 

IO_STATUS Return the process id of the locking process in arg[0] and the interface lock 

coimt in argfl]. If the interface is not locked, return -1 in arg[0]. 



5.19.2 GPJOSIMEOUT 

lO.CONTROL Handle requests to change the timeout value from the default value, one 
hour. The request is made in microseconds. 

When a request times out, an error of ETIMEDOUT is returned to the 
user. 

History: The pre-7.0 GPIO(dev) manpage stated that a timeout value of 
was equivalent to infinity (no transaction would timeout). This is incorrect. 
A timeout value of is equivalent to the default, one hour. The manpage 
has been changed. 

IO.STATUS Return the timeout value, spedfic to this open, in arg[0]. 



5.L9.3 CPIOJVJDTH 

lO.CONTROL Handle requests to set the data path width. The only vabd arguments are 8 
or 16. 
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IO_STATUS Return the width of the data path (either 8 or 16) in jLrg[0]. 



5.1.9.4 CPIOJ1GNALJ4ASK 

IO_CO>nrROL Save the process id and the process interrupt handler. Also, enable the 
27114B to assert ARQ when ATTN is asserted by the device. If signals are 
Bot wanted, the interrupt handler is nulled and the card is disabled from 
asserting ARQ. 

lO^STATUS Return the cause of the interrupt, recorded in int^mask, in arg[0]. For 

27114 users, the only reason for an interrupt can be because ATTN was 
asserted by the device. See gpioO_cvent_from«cam(). 



5.1.9.5 GPIOJETJCONFIG 

lO^CONTROL This request allows the user to configure the 27114B as best suits the 

device. The user creates a mask by OR'ing the following flags (defined in 
gpio.h) as desired, 

PFLG_EDGE_LOGIC - When asserted, data will move on the busy-to- 
ready (or "falling") edge of the handshake signal PFLG. Otherwise data 
will move on the ready-lo-busy (or "rising") edge of PFLG. 

PDIR_OPT.EN - If asserted, the control lines CTL5 and CTL4 v^ill be 
driven with output from the PDIR bit and the HEND bit (both in register 
7), If the flag is not asserted, CTLS and CTL4 will be driver with whatever 
the user writes to the control lines. See section "" for more details. 

PEND_OPT.EN - If asserted, the device can pull the PEND line of the 
front plane which will result in the immediate termination of a data 
transfer. See section "" for more details. 

TRNSFR^CTR^N - If asserted, the driver will enable the transfer counter 
that exists on the 27114B. See section **" for more details. 

Handshake mode. • The choice of handshake is device dependent. There 
are three choices, FULL.MASTER, FULL.SLAVE, or FIFO.MASTER. 
If neither of the three flags is asserted, FIFO.MASTER is used. 



5.1.9.6 GPIOSTLJ.JNES 

lO.CONTROL Handles requests to change the control lines. Since the 27114A has only 3 
control lines the maximum value of those Imes is less than the manmum 
value for the 27114B, which has 6 control lines. 
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5.1.9.1 GPlOJiESET 

lO^CONTROL Wait if another reset is in progress. Otherwise, build and send a 
CIO_CTRL_REQ_MSG to the CAM. Then wait for the 
CIO_CTRL_REPLY.MSG. Once the reply comes, wake any waiting reset 
requests 

Since the hardware has just been reset, any software options associated to 
hardware should also be reset (e.g. shadow re^sters). For historical 
reasons, purely software options remain unchanged (e.g. timeout). 



5.19.8 GPJOJTSMNES 

IG.STATUS Return the value of the status lines in arg[0]. 

51.9.9 GPIOJUETXONFIG 

IO_STATUS Return a configuration mask, of several hardware options, in arg[0]: 
EDGE.LOGIC.SENSE, PDIR_OPT_EN, PEND_OPT_EN, 
TRNSFR_CTR_EN and the handshake mode. The mask definitions are 
the same as in lO.CONTROL GPIO^SET^CONHG. 

51.9.10 GPIOJNTERFACEJYPE 

IO_STATUS Return the value of the id register in arg[0]. 

51.9.11 GPI0JREG7 

lO.STATUS Return the value of the AFl-status register in arg[0]. 

51.9.12 ioj:nvjronment 

This command is a way to perform multiple IO_STATUS commands via one request. When an 
IO.ENVIRONMENT call is made the following information is returned in the env structure: the 
status lines, the interface id for the card, the signal mask, the width of the data path, the locking pid, 
the timeout value and the configuration mask for the card. 

There are other values returned, termj^ason, readjjattem, speed, and dela}\ which have no meaning 
for the 27114B. The values are there for histerical reasons. 
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5.1.10 gpioO_map_crror() 

Hardly used. Should be cleaned up; even tossed. 

5.1.11 gpio0.wait_on_lock() 

Used to time a transaction that is waitbg for a lock to clear before it can access the interface. If the 
interface is not locked, immediately return zero. If the mterface is locked and O.NDELAY was set 
at the time of open, immediately return EACCES. Otherwise, start timing the transaction is 
interrupted by the user (return EINTR). 
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52 Port Server 

The port server, gpioOQ, is the routine to which all messages are delivered. Messages delivered fall 
into three broad classes: 

• Configuration messages from either the configurator or the CAM 

• Dma replies and control replies from the CAM 

• Powerfail and other event notifications from the CAM. 

The port server is simply a switch statement with a separate case for every type of message which 
gpioO will receive. Each case is a procedure caU to the appropriate message handler. Some of the 
cases also set return Jrame to FALSE if the incoming message will be reused by the message handler. 
Unsupported message types are simply dropped. 

The three configuration message handlers - afLdo.bind_msgO, ali_bind_reply_msg(), 
afi_^et_ptr_replyO and gpioO^attachQ - are explained in the configuration section. The powerfail 
recovery process - afi.power_on_req_msgO and afi_pf_get_ptr_rcply() - are explained in the 
powerfail recovery section. The other message handlers - gpioO„reply_from_cam, 
gpio0.event_from_cam and afj_ctrLreply_msg - are explained in the following section. 

52.1 gpio0^reply_firoin_cain() 



A dma reply message, CIO_DMA_REPLY_MSG, is sent by the CAM to gpioO when a dma request 
which gpioO initiated earlier has completed. The processing of the reply depends upon the 
configuration of the 27114B and whether the transaction was a read or a write. 

The basic processing for write transactions (that do not use the counter) and for all read transactions 
is simple. First the untimeout routine is called to release the watchdog timer for this request. 
Second, the buf structure associated with this request is filled in. The bjerror field is set to the status 
of the dma reply. If there was an error, pda->buf.bjlags has the BJERROR bit set. Finally, 
biodoneO is called to awake the sleeping physioQ and return to the user process. 

Some specific handling must be done if PEND was asserted of if the read used the transfer counter. 
For instance, 

• If PEND was pulled, the PEND flipflop must be cleared so the next assertion of PEND will 
register. Also, if PEND was pulled on the write transaction, the FIFO should be cleared. 

• If the counter was used for a read, dear the counter. 

The only other dma transaction to be discussed is the case where the counter is enabled during a 
write tran&ction. This is a special case from the other transactions because the channel may declare 
the transaction complete before it actually is (see the section on write blocking). Because of this 
gpioO can only declare the transaction finished if all the data is off of the card, if PEND was puUed 
or if the dma reply message was received with bad status. 

If PEND was not pulled but data still exists on the card, gpioO must wait for some indication that the 
transfer is indeed complete. To do this, the card is enabled to assert ARQ (when PEND is asserted 
of the transfer counter reaches logical zero) and the state of the driver is set to 
WArnNG.ON.INTR. This way gpioO need not poll the card nor busy-wait for activity. So if ARQ 
is asserted before the timer pops, gpioO receives an event message and can resume completing the 
transaction there. Otherwise, the state WAITTNG^ONJNTR will indicate that the transaction 
should be terminated immediately with an error (that is, an abort message is sot necessary here 
since the dma reply has already been received). 

Note that no error recovery is done by this routine. If an error is returned in the dma reply 
message, it is simply passed up to the user (via the buf structure). The user is responsible for 
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retrying the request, if need be. 

522 gpioO_event_firoin_cain() 

This routmes handles CI0J03VENT messages sent by the CAM to gpioO. The only type of event 
which gpioO will ever receive is an AES ARQ (tMs is the only type the API card can produce). The 
27114B asserts ARQ for 3 reasons, 

• The device asserted ATTN on the frontplane, 

• The device asserted PEND on the frontplane, 

• The transfer counter reached lo^cal zero. 

If the ARQ is due to the device assertmg ATTN on the frontplane, the driver notifies all interrested 
processes of the event via a psignal call; providing interrupt handlers have previously been set up for 
this driver. A search through the per-open table (pot) reveals all interrested processes. If no 
process is interrested in receiving a signal, the event is dropped. Note that when an ARQ occurs, 
the CAM disables the device adapter from ARQing (for historical reasons). Hence the ARQ must 
be re-enabled by the user process after an event occurs. This is accomplished via the ioctl 
GPIO^SIGNAL_MASK. 

If the ARQ is due to PEND assertmg on the frontplane or due to the transfer counter reaching 
logical zero, a DMA transaction just completed. In such case afi_arq_finishQ is called to clean up 
after the DMA (stop the watchdog timer, disable PEND and the transfer counter from causing 
ARQs, figure the dma residue based on the counter, clear the PEND fiipHop, the counter and the 
FIFO) and returns to the user. Note that when an ARQ occurs, the CAM disables the device 
adapter from ARQing (for historical reasons). So if the user previously enabled the card for ATTN 
ARQs, gpioO should re-enable the card to ARQ. Likewise if the card pulled ARQ because of ATTN 
yet the driver is waiting on either a PEND or word counter ARQ to terminate a dma transaction, it 
behooves gpioO to re-enable the card to ARQ. 

The driver deciphers the reason for the ARQ by reading register 7 where there are 3 bits reflecting 
the state of the ATTN flipflop, PEND flipflop and the transfer flipfiop. The 3 bits may indicate thai 
more than one flipflop is set. 

523 afi^ctrLreply^msgO 



Handles CIO.CTRL.REPLY>lSGs that were caused by CIO_CTRL_REQ_MSGs mtending to self 
test (reset) the 27114B. The driver must match any shadow registers to the now default hardware 
configuration. 

S2A afLarq_finish() 



Handles the dean up of DMA transactions that ended via an ARQ on the backplane. This can only 
happen when the driver enables the card to assert ARQ when PEND is asserted by the device or 
when the transfer counter reaches lo^cal zero. 

The driver must figure the residue from the counter, if appropriate, dear the counter, dear the 
PEND flipflop, and dear the FIFO. 
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53 Configuration 

Configuration foUows the standard sequence as defined by the HPIOSD. The sequence is a seven 
part process, 

• gpioO receives a creation message from the Configurator and returns it 

• gpioO receives a do.bind request from the Configurator 

• gpioO sends a bind request to the CAM 

• gpioO receives a bind reply from the CAM 

• ^ioO sends a do_bind reply to the Configurator 

• gpioO sends a control request tot he CAM to get the direct i/o pointer 

• gpioO receives a control request, with the direct i/o pointer, from the CAM 

The creation message is sent to gpioO by the Configurator as the first step in the process. This 
message is used to communicate resource needs and usage options to the system as a whole. GpioO 
fills the message in the standard way and returns. 

The do_bind request message tells gpioO to bmd with a particular lower manager (in this case, the 
CAM). GpioO must do four tasks as a result of a do_bind request. First, save its port number, 
device adapter number, and CAM port number from the do.bind message. Second, set up the 
gpioO.pda.map entry for this instance of gpioO. Third, initialize everything in the pda that needs to 
be set up. Fourth, send a bind request message to the CAM. 

The bind request message to the CAM is used to establish a connection between gpioO and the 
CAM. GpioO tells the CAM what device adapter it wll control and what subqueue the CAM should 
send event messages to. 

The CAM sends a bind reply message to gpioO as a result of the bind request message. GpioO saves 
away the subqueue number which the CAM wants it to use for requests. Then gpioO sends a 
do.bind reply to the Configurator. If the bmd reply message has status CIO.LVLl.CARD, the bind 
was successful and the API card is in the correct slot. Successful binds are followed by the sending 
of a control request to the CAM for grabbing the direct i/o pomter. 

If the bind was unsuccessful (no card was in the slot or the card in the slot was not the API card), 
the control request to get the direct i/o pointer is not done. This instance of the driver v^ill be 
unusable. Note that an attempt is made to get the direct i/o pointer again on a powerfail. This 
implies that an API card can be added to the system on the fly during a power failure. 

If the bind was successful, eventually a control reply is received from the CAM. If the status of the 
control reply is LLIO.NORMAL, the direct i/o pointer is saved in the pda and the HDWR.DEAD 
bit of pda->flags is turned off. This instance of gpioO can now be used. 

53.1 afLdo.bind.iiisg() 

Handles the DO_BIND.RECLMSG received from the Configurator. First, gpioO saves the 
information about its lower manger. Then gpioO initializes its pda values. Finally, gpioO builds and 
sends a BIND_RECLMSG to the CAM. 



532 ari_bind.reply.msg() 

Handles BIND.REPLY.MSG from the CAM. Once this message is received with good status, 
binding between the CAM and the GPIO monolith is complete. GpioO then builds and sends a 
do.ctrLrcq message to the CAM. This is to request its direct i/o pointer. Because there are 
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multiple functions for a cio^ctrLreq message, change the state to indicate how the cio_ctrLreply 
message should be handled. 

Should the BIND_REPLY_MSG be received from the CAM with bad status, binding has failed. A 
do_bind.repIy message is built and sent to the Configurator and configuration is complete. Set the 
state to indicate this instance of gpioO can not be used if opened. 



533 an_getjptr_reply() 

Handles the aO.CTRL_REPLY.MSG that was caused by the CIO.CTRL.REQ.MSG sent during 
configuration. If the do.ctrLrcply message is received with good status AND the message indicates 
the device adapter in the slot is a level 1 type card, the message contains a valid direct i/o pointer 
for gpioO. Save the pointer, use the pointer to enable the card to function, complete configuration by 
sending a do_bind_reply message to the Configurator and declare the driver usable by clearing the 
HDWT^_DEAD bit from the pda flags. 



S3 A gpioO_attach() 

This routines finds a mapping between the device adapters lu number and a pda. A routine from 
the old days, it should be replaced by a call to port joJndex(). 



34 HP Confidential 



HP-UX CIO GPIO MonoUth 



5.4 Powerfail Processing 

The driver must do special prcx«ssmg whenever powerfail occurs. The driver is notified of a 
powerfail by the receipt of a POWER.ON_REQ_MSG from the CAM. The CAM sends the power- 
on request message to gpioO after power is restored. 

No special processing of outstanding requests to the CAM is needed. The CAM guarantees closure 
on all requests that arc sent to it. If a request was active at the time of the power failure, a dma 
reply (with powerfail aborted status) will eventually be sent to gpioO. This rely can be handled in the 
normal course of handling dma replies. An error will be returned to the user process. 

Note that gpioO does not do any real recovery from a powerfail. For the most part, the user process 
is responsible for setting up the card again (if it needs something other than power-on state). In 
addition, the user process must set up the device attached to the AFI card. 

5.4.1 afLpower„on.req_iiisg() 

GpioO must send a POWER^ON^REPLY^MSG to the CAM as soon as the power-on request 
message is received. In addition, gpioO attempts to re-establish a valid direct i/o pointer via a CIO 
control request message to the CAM. This is also important if the system was initially brought up 
with either no card m the AFI slot or the wrong card in the slot. It is, therefore, possible to add the 
AH card to the system during powerfail and have it work. 

SA2 ari_pr_get_ptr_reply() 

Once the control reply is received with good status and the status indicates the card is a 27114B, the 
direct i/o pointer is considered valid. The card is then reset and enabled. 

The reset is an important part of the handling of emulated Fatal Error mode: 

HPPB drivers own a page of i/o space and are responsible for checking to see when their page is in 
FE mode; eventually clearing the FE bit. 

However, CIO drivers do not own an entire page of I/O space. Each page is shared by multiple 
drivers. Therefore CIO drivers, not knowing the progress of other drivers, can not clear the page FE 
bit; the CAM does. 

This brings us to the interesting AFI case of why an explicit reset (one done by touching i/o space 
rather than by sending a control request to the CAM) is necessary in AFI powerfail. 

Suppose gpioO is in the middle of a transaction at the time powpr fails. Once power is restored, the 
transaction resumes where it left off; gpioO's power on request message will be queued. If the CAM 
has already taken the page which the API belongs to out of FE mode, the transaction can now touch 
the i/o space; the page that gpioO's address space belongs in will no longer be marked FE mode. 
Since we rely on the card being in default configuration after a power failure, it should be reset to 
guarantee that default state. 

After resetting the card, gpioO must restore the states of software values relating to hardware 
configuration. 
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6. Testing 

GpioO should be tested in four different ways: 

• Instruction Coverage Analysis (ICA) 

• Configuration Testing 

• Stress Testing 

• Powerfail Testing 

ICA is done to verify that all the code actually gets executed at least once. This approach has 
definite limitations. For instance, ICA may mdicate the code was hit, but you will not know that it 
was hit while the driver /card was in different states. The goal is 100% measured coverage. 

Configuration testing means building several systems with different properties. For example, 

• Build a system with no gpioO configured. Make sure that it boots normally. 

• Build a system with several gpioO's. Make sure that they are all usable. 

• Build a system with gpioO's on a second channel. Make sure they are usable. 

• Build a system with one gpioO. Try booting without a card in the slot, with different cards in the 
slot and with an API card in the slot. 

Stress testing involves lots of activity simultaneously on one or more cards. For example, try lots of 
i/o to one card with two different processes. 

Powerfail testing can be done by power cycling the processor while the card is idle, busy with 
different requests, and not present. Make sure multiple powerfails work. 

A test suite does exist for gpioO. All tests in the suite should pass after any change is made. New 
tests should be added as features are added or changed. Currently the suite is in 
Wayback:/mnt/azure/suzyz/tests/scaffold. 
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Appendix I: Diagnostic loctis 

Certain iocti calls are only allowed if gpioO has been opened in diagnostic mode. If a non-diagnostic 
attempts to invoke any of these calls, EINVAL is returned. These caUs involve direct register reads 
and writes. Therefore, the diagnostic program has complete control of the afi card. It is the 
diagnostic program's responsibility to put the AFI card back into a good state before it exits. This 
can be done by resetting the AFI card. 

lO^CONTROL requests write to the specified register with the value passed in arg[0]. IO.STATUS 
requests read the specified register in arg[0]. 



'I>pc 

lO.CONTROL 
lO.CONTROL 
lO.CONTROL 
lO.CONTROL 
lO.CONTROL 
IO_CONTROL 

lO.STATUS 
lO.STATUS 
lO.STATUS 
lO.STATUS 
lO.STATUS 
lO.STATUS 
lO.STATUS 
lO.STATUS 
lO.STATUS 



Command 

GPIO.REG0 

GPI0.REG1 

GPI0.REG7 

GPIO.CLEAR 

GPIO.REGA 

GPIO.REGB 

GPIO.REGO 

GPIO.REGl 

GPIO.REG3 

GP10.REG7 

GP10.REG9 

GPIO.REGA 

GPIO.REGB 

GPIO.POLL 

GPIO.PORTNUM 



Description 

write register ~ data renter 

write register 1 - CIO control register 

write register 7 - 27114 control I register 

dear data path ~ clear fifo, re-enable fifo 

write register A - transfer ctr 

write register B - transfer ctr/27114 control II 



read register - 
read register 1 - 
read register 3 - 
read register 7 - 
read re^ster 9 
read register A 
read register B 
return whether 
return the port 



data register 
CIO sense register 
ID re^ster 

- 27114 status register 
~ CIO status register 
~ low and mid bytes of counter 

- high byte of counter 
the card is ready for bus requests 
number for this interface 
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Appendix II: Message Formats 



•** 

•** 
•** 



All of the messages and constants explained here 
are located in one of the two following files, 

sio/llio.h 
sio/iocam.h 

These files are the final authority for message 
layout and constants. 



/** Standard header for all messages **/ 



typedef struct { 

shortint 

shorlint 

int 

port_num_type 
} llio_std_header_type; 



msg_descriptor; 
messagejd; 
transaction_num; 
from_port; 



/** Message descriptors used by gpioO **/ 

#define CREATION^MSG 2 

#define DO.BIND-REQ.MSG 3 

#define DO_BIND_REPLY_MSG 4 

#define BIND.REQ.MSG 5 

#define BIND.REPLY_MSG 6 

#define CIO.DMAJO_REQ.MSG 100 

#define CIO.DMAJOJlEPLY.MSG 101 

#define CIO.CTRL.REQ.MSG 102 

#define CIO.CrRL.REPLY.MSG 103 

#define CIOJO.EVENT.MSG 104 

#define POWER.ONJlEQ.MSG 17 

#define POWER.ON.REPLYJV1SG 18 

#define TIMER.EVENT.MSG 19 
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/** Configuration messages **/ 



typedef struct { 

creation_options 

int 

int 

mt 

bits 

port_num_type 
} acation_mfo_type; 

typedef struct { 

io_subq_type 

port_num_type 

int 

int 

int 

port_num_type 

mt 
} do3ind_req_type; 



creatc.options; 

8crvcr_data.len; 

ma}L.msg_size; 

num.msgs; 

num.subqueues; 

port_num; 



rcply_subq; 

mgr_port_num; 

config_addr_3; 

conrig_addr_2; 

config_addr_l; 

lm_port_num; 

load_info; 



typedef struct { 

■' lJio_status_type 
} do_bind_reply_type; 

typedef struct { 

io_subq_type 
io_subq_type 
shortinL 
shortint 

int 

int 

int 

} bmd_req_type; 

typedef struct { 

llio_status.type 

int 

shortint 

io^subq^type 

io.sub4.type 

unsigned dhar 

unsigned char 

} bind_rcply_type; 



reply.status; 



reply.subq; 

hm.event_.subq; 

hm_subsys_num; 

hm_m eta Jang; 

hm^rev.code; 

hm_config_addr_3 

hm_conrig..addr.2: 

hm_config_addr_l 



rcply^status; 

lm_rev.code; 

lm_queue.depth; 

lmJow.req_subq; 

lnijii.req.subq; 

lm.fTCCze_data:l; 

Imjdignment:!; 
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/** DMA request and reply messages **/ 



typedef struct { 

io_subq„type 

bits 

do_vquad_ptr 

} cio_dma«Teq_type; 



rcply^subq; 
da^number; 
vquad.chain; 



typedef struct { 

llio_status_type 
do«vquad_ptr 

} cio_dma_reply.type; 



Uiojstatus; 
vquad_chain; 



/** Quads and DMA commands **/ 



typedef struct cio_vquad_type { 




cio.cmdjype 


command; 


int 


count; 


int 


residue; 


struct cio.vquad^type 


♦link; 


data.ptr^type 


buffer; 


addr_class_type 


addr^class; 


} cio_vquad_type; 




typedef do_vquad_type 


*cio_vquad_ptr; 



typedef union { 




int 


do_cmd; 


struct { 




bits 


order; 


unsigned 


suppression:2; 


unsigned 


logcli_break:l; 


unsigned 


blocked:!; 


unsigned 


reserved:!?; 


unsigned 


read_write:!; 


unsigned 


continue.dma:!; 


unsigned 


exact:!; 


}u; 




} do_cmd_typc; 





/♦• CIO orders ••/ 

#derme CIO.RD.WORD.ORDER 0x60 
#derme QO.WD.WORD.ORDER 0x70 
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/** lO Event Message **/ 



typedef struct { 
int 


event; 


union { 
int 

bit8 

}u; 

} cioJo_evcnt_type; 


int_info[(3) + ll; 
byte.infoI(15) + l]; 



#defme CIO_ARQ.STATUS 



/•* CIO control request and reply messages **/ 

typedef struct { 

io_subq_type reply.subq; 

bits da_number; 

bits ctrLfunc; 

int ctrLparm; 
} cio_ctrl_req_type; 

typedef struct { 

llio_status_type llio_status; 

int ctrljnfo; 

int extrajnfo; 

} cio_ctrLreply_t>pe; 

#defme CIO.DA.SELFTEST 2 

#derine CIO_GET_DIRECTJO_PTR 10 



typedef struct do_ 


.quadrant { 




volatile int 




rsvdl[31; 


volatile int 




normal; 


volatile int 




rsvd2[3]; 


volatUe int 




cend; 


volatile int 




rsvd3[3]; 


volatile int 




cbyte; 


volatile int 




rsvd4[3); 


volatile int 




ccndbyte; 



typedef struct ciodio { 

struct do.quadrant 
struct do.quadrant 
struct do.quadrant 
struct do.quadrant 

} dodio; 



data; 
ctlsens; 
order; 
statcmd; 
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